====== mailSend() ======

''void **mailSend**(string //E-Mail//, int //SerienmailID//, [int //Zeitpunkt//], [string //Link//], [string //C1//, string //C2//, string //C3//, string //C4//, string //C5//])''

''void **mailSend**(string //E-Mail//, int //SerienmailID//, array //Einstellungen//)''

Die Funktion ''mailSend()'' verschickt die Serienmail mit der Kennung //SerienmailID// sofort oder zu einem definierten Zeitpunkt an eine vorgegebene E-Mail-Adresse. Die E-Mail-Adresse muss -- anders als bei den Funktionen ''[[:de:create:functions:mailResume]]'' und ''[[:de:create:functions:mailSchedule]]'' -- nicht in der Adressliste des Befragungsprojekts bekannt sein.

  * //E-Mail//\\ E-Mail-Adresse, an welche die E-Mail verschickt werden soll.
  * //SerienmailID//\\ Numerische Kennung der Serienmail, die verschickt werden soll.
  * //Zeitpunkt// (optional)\\ Entweder die Verzögerung bis zum Versand (in Sekunden, maximal 153900000) __oder__ ein Unix-Zeitstempel, der den Zeitpunkt für den nächsten Versand definiert.
  * //Link// (optional)\\ Der Link, der in der Serienmail für den Platzhalter ''%link%'' verwendet wird. Falls kein Link angegeben wird, wird der [[:de:survey:url]] ohne weitere Spezifikation eines Fragebogens verwendet.
  * //C1// bis //C5// (optional)\\ Wenn Sie hier einen Text angeben (optional), können Sie diesen Text mithilfe der Platzhalter ''%custom1%'' bis ''%custom5%'' in der Serienmail verwenden. In Verbindung mit ''value()'' können Sie beispielsweise Antworten aus dem laufenden Interview in der E-Mail anzeigen.
  * //Einstellungen// (optional)\\ Wenn als dritter Parameter ein Array übergeben wird, so werden die weiteren Einstellungen aus diesem Array entnommen. Folgende Schlüssel sind möglich:
    * '''sendtime''' -- entspricht dem Parameter //Zeitpunkt//
    * '''update''' -- Standardmäßig wird mit jedem Aufruf von ''mailSend()'' eine E-Mail versendet. Wenn für '''update''' ein Wert festgelegt ist und es wurde in dem Befragungsprojekt mit ''mailSend()'' bereits eine E-Mail für den Versand geplant (noch nicht versandt), welche denselben Wert für '''update''' enthält, dann wird der Versandtermin und alle Daten aktualisiert anstatt eine weitere E-Mail vorzubereiten. Wenn Sie z.B. nur eine E-Mail pro Interview versenden möchten, dann verwenden Sie z.B. ''%%'update' => caseToken()%%''.
    * '''%link%''' -- entspricht dem Parameter //Link//
    * '''%custom1%''' bis '''%custom5%''' -- Inhalte für die gleichnamigen Platzhalter in der Serienmail
    * '''attach''' -- Variablenkennung (string) oder mehrere Kennungen (array) hochgeladener Dateien (Frage vom Typ "Datei hochladen"), welche an die E-Mail angehängt werden sollen. Geben Sie im Array einen Schlüssel an, um den Dateinamen für den Dateianhang festzulegen.

===== Hinweise =====

  * Mit der Funktion ''mailSend()'' kann pro Interview eine bestimmte Serienmail nur einmal an eine bestimmte E-Mail-Adresse verschickt werden.
  * Innerhalb eines Interviews können mittels ''mailSend()'' maximal 20 E-Mails verschickt werden.

===== Beispiel 1 =====

Im Interview soll die E-Mail-Adresse eines Kollegen abgefragt, aber nicht gespeichert werden. An die E-Mail-Adresse soll eine Einladung mit Verweis auf das aktuelle Interview (Fall-Nummer CASE) verschickt werden.

**Hinweis:** Dieser Anwendungsfall lässt sich i.d.R. einfacher mit einer Frage vom Typ [[:de:create:questions:email]] und ganz ohne PHP-Code umsetzen. Hier ist nur eine alternative Lösung mittels ''mailSend()'' dargestellt.

Um die E-Mail-Adresse abzufragen, wird auf Seite 5 im Fragebogen ein HTML-Eingabefeld im Fragebogen platziert.

<code html>
<div>
  E-Mail-Adresse des Kollegen:
  <input type="text" name="email_colleague" style="width: 160px" />
</div>
</code>

Auf der folgenden Fragebogen-Seite (nicht später!) wird die angegebene E-Mail-Adresse mittels ''[[:de:create:functions:readget]]'' ausgelesen und die Serienmail mit der Kennung ''2'' an diese E-Mail-Adresse verschickt. Im Link zum Fragebogen wird die aktuelle Fall-Nummer als Referenz angehängt.

<code php>
$email = readGET('email_colleague', false);
if (trim($email) !== '') {
  $link = 'https://www.soscisurvey.de/PROJEKT/?r='.caseNumber();
  mailSend($email, 2, 0, $link);
}
</code>


===== Beispiel 2 =====

Ein Teilnehmer füllt einen Test aus, der Punktwert wurde in Variable ''$points'' berechnet und soll nun zusammen mit der Teilnehmern-Kennung (SERIAL) an eine Mailadresse geschickt werden, damit der Forscher automatisch über abgeschlossene Tests informiert wird.

Dafür wurde unter **Einladungen verschicken** -> **Serienmails** eine Serienmail (ID 1) angelegt, die u.a. folgenden Inhalte hat:

<code>
Teilnehmer: %custom1%
Testergebnis: %custom2%
</code>

Auf der letzten Seite des Fragebogens würde nun unter der Berechnung des Punktswerts (''$points'') folgender PHP-Code platziert, um das Ergebnis an ''store@example.com'' zu senden.

<code php>
mailSend('store@example.com', 1, 0, NULL, caseSerial(), $points);
</code>